USBGetFullConfigurationDescriptor

The USBGetFullConfigurationDescriptor function returns the entire block of configuration data from the specified device and any associated descriptors, which includes interface and endpoint descriptors, and all of the information that pertains to them. The configuration data returned by the USBGetFullConfigurationDescriptor function is suitable for use with the USBFindNextInterfaceImmediate and the USBFindNextEndpointImmediate functions.

OSStatus USBGetFullConfigurationDescriptor(USBPB *pb)

Required fields in the USBPB parameter block for the USBGetFullConfigurationDescriptor function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

--> usbFlags

Should be set to 0

--> usbReference

Device reference

--> usbWValue

Configuration index

<-- usbBuffer

Points to a configuration descriptor structure

<-- usbActCount

Size of descriptor returned

The USBGetFullConfigurationDescriptor function determines the size of a full configuration descriptor, including all interface and endpoint descriptors for a given configuration, allocates memory for the configuration descriptor, and reads all the descriptors in.

You don't pass the USBGetFullConfigurationDescriptor function a buffer pointer, the function allocates one and passes a pointer back in the usbBuffer field of the parameter block. The memory for the configuration descriptor must be deallocated when the information is no longer needed. The USBDeallocMem function should be used in the class driver's finalize routine for deallocating memory and disposing of the descriptor.

The USBGetFullConfigurationDescriptor function is unusual in that it takes a configuration index in the usbWValue field rather than a configuration value. The configuration value is found in the configuration descriptor, and is not available until the descriptor has been read. The configuration index refers to the 1st, 2nd, 3rd, or greater configuration descriptor in a device by specifying 0, 1, 2, or greater respectively. The configuration index is independent of the configuration value found in the configuration descriptor. The configuration value is used as an input parameter to set the configuration for a device.

Currently there are no other functions in the USB configuration services that provide the same functionality as the USBGetFullConfigurationDescriptor function. Configuration descriptors can be retrieved using the USBGetConfigurationDescriptor function, but the driver has to find the length of the configuration descriptor and allocate the memory for the descriptor when calling the function. Specific types of descriptors can be found with the USBFindNextAssociatedDescriptor function.

Once you have obtained the configuration descriptor, you need to find the interface you're interested in within the configuration descriptor by using the USBFindNextInterfaceDescriptorImmediate function.

USBFindNextInterfaceDescriptorImmediate

The USBFindNextInterfaceDescriptorImmediate function returns the address to the next interface descriptor in a specified configuration descriptor.

OSStatus USBFindNextInterfaceDescriptorImmediate(USBPB *pb)

Required fields in the USBPB parameter block for the USBFindNextInterfaceDescriptorImmediate function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

<--> usbBuffer

--> Configuration descriptor <-- Interface descriptor

--> usbFlags

Should be set to 0

<-- usbActcount

Length of interface descriptor found

<--> usbReqCount

--> 0, This should be set to 0 the first time the call is made. Otherwise, the value from the last call should be left alone. <-- Offset of this descriptor from the start of the configuration descriptor

<--> usbClassType

--> Class; 0 matches any class <-- Class value for interface found

<--> usbSubclass

--> Subclass; 0 matches any subclass <-- Subclass value for interface found

<--> usbProtocol

--> Protocol; 0 matches any protocol <-- Protocol value for interface found

<--> usbWValue

--> 0 Configuration number: If more than one interface is described in the configuration descriptor, this field specifies the absolute number of the interface in the list.

<-- usbWIndex

Interface number

<-- usbOther

Alternate interface

The usbReqCount field should be set to 0 for the first iteration of this call. For each subsequent call to the USBFindNextInterfaceDescriptorImmediate function, usbReqCount contains the offset of the current interface descriptor from the beginning of the configuration descriptor.

The usbBuffer field should be assigned the address of the start of the configuration descriptor obtained from a call to the USBGetFullConfigurationDescriptor function. This must be the full configuration descriptor returned by USBGetFullConfigurationDescriptor . The usbBuffer is assigned a pointer to the next interface descriptor within the specified configuration for each subsequent call to the USBFindNextInterfaceDescriptorImmediate function.

The usbClass, usbSubclass, and usbProtocol fields should contain either specific class, subclass, and protocol numbers, or contain 0 to use for a wildcard search if the caller wants to find an interface regardless of these fields. Upon return, these fields contain the class, subclass, and protocol values for the next interface found. If the caller wants to perform a wildcard search again, the wildcard values must be reset, because these fields are filled in with the returned values from the last call.

Once you've found an interface in the device, you need to find the endpoints that make up that interface.

If no interface is found that matches the requested interface, kUSBNotFound is returned.

The errors returned by the USBFindNextInterfaceDescriptorImmediate function include:

kUSBNotFound	interface specified is not in configuration
kUSBInternalErr, paramErr	not a valid configuration descriptor

USBFindNextEndpointDescriptorImmediate

The USBFindNextEndpointDescriptorImmediate function returns the address to the next endpoint descriptor in a configuration descriptor that follows a specified interface descriptor. This is a synchronous call.

OSStatus USBFindNextEndpointDescriptorImmediate(USBPB *pb)

Required fields in the USBPB parameter block for the USBFindNextEndpointDescriptorImmediate function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

<--> usbFlags

--> Direction of endpoint ( kUSBIn, kUSBOut, or kUSBAnyDirn ) <-- Direction is returned here if kUSBAnyDirn is used in the usbClassType field. Note that if kUSBAnyDirn is specified, this field is altered on the calls return. If you want to make another call to find an endpoint of any direction, kUSBAnyDirn must be specified again. Direction is also returned if kUSBIn or kUSBOut are specified. It will however, be the same value as that passed in.

<--> usbBuffer

--> Interface descriptor on the first call, points to an endpoint descriptor on subsequent calls <-- Endpoint descriptor

<--> usbReqCount

Offset of interface or endpoint descriptor in configuration descriptor

<-- usbActcount

Length of endpoint descriptor found

<--> usbClassType

--> Specific endpoint type, or kUSBAnyType as wildcard <-- Endpoint type

<--> usbOther

--> Endpoint number, always pass 0 unless you want to match a specific endpoint number. <-- Next matching endpoint is returned

<-- usbWValue

Maximum packet size of endpoint

The usbBuffer should be assigned the address of the start of the interface descriptor obtained from a call to the USBFindNextInterfaceDescriptorImmediate function. For each subsequent call to USBFindNextEndpointDescriptorImmediate, usbBuffer is assigned a pointer to the next endpoint descriptor within the specified interface.

The errors returned by the USBFindNextEndpointDescriptorImmediate function include:

kUSBNotFound	-6987	endpoint specified is not in configuration
kUSBInternalErr, paramErr	-6999	not a valid configuration descriptor